<?xml version="1.0" encoding="UTF-8" ?>
<!--

    ﻿Copyright (C) 2009-2013 NewMain Softech

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
    either express or implied. See the License for the specific language
    governing permissions and limitations under the License.

-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>TimerController</title>
</head>

<body>
<h3>TimerController</h3>
<p><h4>Introduction</h4>
TimerController component provides means to cancel specific timer event as well as repeated scheduling. 
Also one of implementation ways uses the injection style and brings the benefits of it to your code: 
flexibilities of  switching different timer-event schedule management easily, common coding style for 
the client side and the server side (thought it does not provide unified timer event system between 
client and sever). And may make code changes less even for the case like later having to change which 
side of timer (client or server) to trigger timer event.<br />
<br />
TimerController component is represented by the following interfaces:
<ul>
	<li>Timer event scheduler side
		<ul>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html"
				><code>TimerController</code></a>
			</li>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerInjector.html"
				><code>TimerControllerInjector</code></a>
			</li>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactory.html"
				><code>TimerControllerFactory</code></a>
			</li>
		</ul>
	</li>
	<li>Timer event consumer side
		<ul>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerEventListener.html"
				><code>TimerEventListener</code></a>
			</li>
		</ul>
	</li>
</ul>
The following out-of-box implementations are provided as default implementations:
<ul>
	<li>For non-injection way
		<ul>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/TimerSingletonController.html"
				><code>TimerSingletonController</code></a><br />
				This is only for client side usage. This is typical singleton pattern class in order to 
				eliminate effort of managing multiple schedulers  (controllers) by using this class.
			</li>
		</ul>
	</li>
	<li>For injection way
		<ul>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerImpl.html"
				><code>TimerControllerImpl</code></a> : Default client-side implementation of <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html"
				><code>TimerController</code></a> interface.
			</li>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerUniInstanceHolder.html"
				><code>TimerControllerUniInstanceHolder</code></a> : Holder of final single <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerImpl.html"
				>TimerControllerImpl</a> instance (seim-singleton); alternative to singleton pattern. The use of this can 
				eliminate the effort of managing multiple <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html"
				><code>TimerController</code></a> instances (for client side).
			</li>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerGinModule.html"
				><code>TimerControllerGinModule</code></a> : Gin module to inject <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerImpl.html"
				><code>TimerControllerImpl</code></a> instance (for client side).
			</li>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerUniControllerGinModule.html"
				><code>TimerUniControllerGinModule</code></a> : Gin module to inject <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerImpl.html"
				><code>TimerControllerImpl</code></a> instance from <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerUniInstanceHolder.html"
				><code>TimerControllerUniInstanceHolder</code></a> (for client side).
			</li>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactoryImpl"
				><code>TimerControllerFactoryImpl</code></a> : With default configuration, this will 
				instantiate <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html"
				><code>TimerController</code></a> object for client-side; it will be instantiated by <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerGinModule.html"
				><code>TimerControllerGinModule</code></a> class (via <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerGinjector"
				><code>TimerControllerGinjector</code></a> class). Instead, to obtain semi-singleton 
				<code>TimerController</code> instance, set custom <code>TimerControllerGinjector</code> 
				implementation to <code>TimerUniControllerGinModule</code>, and set it to 
				<code>TimerControllerFactoryImpl</code> instance. To yield <code>TimerController</code> 
				instance for server-side, develop custom <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerInjector.html"
				><code>TimerControllerInjector</code></a> implementation and set it by <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactoryImpl.html#setTimerControllerInjector(com.newmainsoftech.gwetons.shared.timer.TimerControllerInjector)"
				><code>setTimerControllerInjector</code></a> method.
			</li>
			<li><a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactoryUniInstanceHolder.html"
				><code>TimerControllerFactoryUniInstanceHolder</code></a> : Holder of final single static 
				<a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactoryImpl"
				><code>TimerControllerFactoryImpl</code></a> instance (semi-singleton) with default setting. <br /> 
				If default setting of <code>TimerControllerFactoryImpl</code> class is enough, then it is 
				sufficient to use this class in order to instantiate <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html"
				><code>TimerController</code></a> object via single (semi-singleton) 
				<code>TimerControllerFactoryImpl</code> instance held in this class.
			</li>
		</ul>
	</li>
</ul>
</p>
<p><h4>Usage guide</h4>
<ul>
	<li><b>Timer controller side</b><br />
		<ul>
			<li>For non-injection way<br />
				Just use <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/TimerSingletonController.html"
				><code>TimerSingletonController</code></a>. Or create <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html"
				><code>TimerController</code></a> implementation class of your own, and use it.</li>
			<li>For injection way<br />
				Configure <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactory.html"
				><code>TimerControllerFactory</code></a> instance.
				<ul>
					<li>When the <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactoryImpl"
						><code>TimerControllerFactoryImpl</code></a> out-of-box implementation is sufficient enough, 
						then use <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactoryUniInstanceHolder.html"
						>TimerControllerFactoryUniInstanceHolder</a>. 
					</li> 
					<li>When need customization more than out-of-box default configuration:<br />
						Implements customization from the followings as necessity bases. 
						<ul>
							<li>To concentrate timer scheduling to single <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerImpl.html"
								><code>TimerControllerImpl</code></a> instance, create <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerGinjector"
								><code>TimerControllerGinjector</code></a> implementation for <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerUniControllerGinModule.html"
								><code>TimerUniControllerGinModule</code></a>, and set it by <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactory.html#setTimerControllerInjector(com.newmainsoftech.gwetons.shared.timer.TimerControllerInjector)"
								><code>setTimerControllerInjector</code></a> method of 
								<code>TimerControllerFactory</code> instance of your choice.
							</li>
							<li>When <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/client/timer/TimerControllerImpl.html"
								><code>TimerControllerImpl</code></a> does not full fill your needs (such as for 
								server-side)
								<ul>
									<li>Create your custom implementation of <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html"
										><code>TimerController</code></a> interface.
									</li>
									<li>Create <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerInjector.html"
										><code>TimerControllerInjector</code></a> implementation class for your 
										custom <code>TimerController</code> class, and set the 
										<code>TimerControllerInjector</code> implementation by <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactory.html#setTimerControllerInjector(com.newmainsoftech.gwetons.shared.timer.TimerControllerInjector)"
										><code>setTimerControllerInjector</code></a> method of 
										<code>TimerControllerFactory</code> instance of your choice. 
									</li>
								</ul>
							</li>
						</ul>
					</li>
				</ul>
			</li>
		</ul>
	</li>
	<li><b>Timer event listener (consumer) side</b>
		<ol>
			<li>Create your custom implementation of <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerEventListener.html"
				><code>TimerEventListener</code></a> interface of what <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerEventListener.html#fire()"
				><code>fire()</code></a> will be called at scheduled time.
			</li>
			<li>Obtain <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html"
				><code>TimerController</code></a> instance. <br /> 
				In the injection way, get it by <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactory.html#getTimerControllerInstance()"
				><code>getTimerControllerInstance</code></a> method of available <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerControllerFactory.html"
				><code>TimerControllerFactory</code></a> instance.
			</li>
			<li>Schedule your <code>TimerEventListener</code> instance by <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html#schedule(com.newmainsoftech.gwetons.shared.timer.TimerEventListener,%20int)"
				><code>schedule</code></a> method or <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html#scheduleRepeating(com.newmainsoftech.gwetons.shared.timer.TimerEventListener,%20int)"
				><code>scheduleRepeating</code></a> method of the obtained <code>TimerController</code> 
				instance.
			</li>
			<li>To cancel the scheduled timer for the <code>TimerEventListener</code> instance, give the 
			  	<code>TimerEventListener</code> instance to <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html#cancel(com.newmainsoftech.gwetons.shared.timer.TimerEventListener)"
			  	><code>cancel</code></a> method of the used <code>TimerController</code> instance. Or you 
			  	may use <a href="https://gwetons.googlecode.com/svn/site/apidocs/com/newmainsoftech/gwetons/shared/timer/TimerController.html#cancelAll%28%29"
			  	><code>cancelAll</code></a> method to cancel all scheduled timers with the <code>TimerController</code> 
			  	instance.
			</li>
		</ol>
	</li>
</ul>
</p>
</body>
</html>